/**
 * Utilities and Tools that makes XML parsing and validation more easier.
 * 
 * There are two ways to use this package:
 * <ul>
 *   <li>Static methods in <code>XMLTools</code></li>
 *   <li>Instance of <code>XMLUtilities</code> class</li>
 * </ul>
 * 
 * Static methods are good for simple usages. It shares one internal instance
 * of XMLUtilities.
 * 
 * Standalone XMLUtilities instance is good for multi-threading environment,
 * is a little bit faster and finally&mdash;simplifies usage because of
 * each method&mdash;in contrast to appropriate static method in
 * XMLTools&mdash;throws less exceptions.
 * 
 * <hr />
 * 
 * <h3>Functions, Methods and Tools</h3>
 * 
 * <table border="1" cellpadding="5" cellspacing="0">
 *   <thead>
 *     <tr>
 *       <th rowspan="2">Category</th>
 *       <th rowspan="2">Method</th>
 *       <th colspan="2">Availablity</th>
 *     </tr>
 *     <tr>
 *       <th>in <code>XMLUtilities</code></th>
 *       <th>in <code>XMLTools</code></th>
 *     </tr>
 *   </thead>
 *   <tbody>
 *     <tr>
 *       <td rowspan="4">XML Loading</td>
 *       <td>from File to Document</td>
 *       <td align="center">X</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td>from Stream to Document</td>
 *       <td align="center">X</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td>from String to Document</td>
 *       <td align="center">—</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td>from String to Source</td>
 *       <td align="center">—</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td rowspan="3">Conversions</td>
 *       <td>Document to Source</td>
 *       <td align="center">—</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td>Document to String</td>
 *       <td align="center">X</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td>Source to String</td>
 *       <td align="center">X</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td>Validation</td>
 *       <td>XML validation against XMLSchema</td>
 *       <td align="center">X</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td rowspan="2">XPath evaluation</td>
 *       <td>evaluate XPath that results to NodeList</td>
 *       <td align="center">X</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td>evaluate XPath that results to single Node</td>
 *       <td align="center">X</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td rowspan="4">Transformation</td>
 *       <td>from Sources to Document</td>
 *       <td align="center">X</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td>from Templates and Source to Document</td>
 *       <td align="center">X</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td>from Sources to String</td>
 *       <td align="center">X</td>
 *       <td align="center">X</td>
 *     </tr>
 *     <tr>
 *       <td>from Templates and Source to String</td>
 *       <td align="center">X</td>
 *       <td align="center">X</td>
 *     </tr>
 *   </tbody>
 *   <tfoot>
 *     <tr>
 *       <th colspan="4">Legend</th>
 *     </tr>
 *     <tr>
 *       <th>—</th>
 *       <td colspan="3"><em>Not available</em></td>
 *     </tr>
 *     <tr>
 *       <th>X</th>
 *       <td colspan="3"><em>Available</em></td>
 *     </tr>
 *   </tfoot>
 * </table>
 * 
 * <hr />
 * 
 * <h3>XML Loading</h3>
 * 
 * The routines are defined in <code>XMLTools</code> and partially in
 * <code>XMLUtilities</code>. The names of the methods starts with
 * <code>loadDocument</code> or <code>loadSource</code>.
 * 
 * <br />
 * 
 * The following example loads XML content from specified resource. The static
 * method returns <code>Document</code> and throws two Exceptions:
 * <dl>
 *   <dt><code>NoSuchResourceException</code></dt>
 *   <dd>if the resource does not exist</dd>
 *   <dt><code>XMLLoadingException</code></dt>
 *   <dd>this exception coveres all "technical" exceptions</dd>
 * </dl>
 * 
 * <a name="xmlloadingexample" />
 * 
 * <pre style="border:1px solid black">
package global.sandbox.xmlutilities.demo;

import global.sandbox.xmlutilities.XMLTools;
import java.io.IOException;
import java.io.InputStream;
import org.w3c.dom.Document;

public class XMLLoading {
    
    public static Document loadXMLFromResourceAsDocument(Class clazz, String name)
            throws NoSuchResourceException, XMLLoadingException {
        InputStream is = clazz.getResourceAsStream(name);
        
        if (is == null) {
            throw new NoSuchResourceException(name);
        }
        
<span style="background-color: rgb(255,255,200)">        try {
            return XMLTools.loadDocumentFromStream(is);
        } catch (Exception ex) {
            throw new XMLLoadingException(ex);
        } finally {
            try {
                is.close();
            } catch (IOException ex) {
                throw new XMLLoadingException(ex);
            }
        }</span>
    }
    
    public static class NoSuchResourceException extends Exception {
        
        private static final long serialVersionUID = 1L;
        
        public NoSuchResourceException(String resourceName) {
            super(resourceName);
        }
        
    }
    
    public static class XMLLoadingException extends Exception {
        
        private static final long serialVersionUID = 1L;
        
        public XMLLoadingException(Throwable cause) {
            super(cause);
        }
        
    }
    
}
 * </pre>
 * 
 * <h3>Conversions</h3>
 * 
 * <code>XMLTools</code> allows you to convert <code>Document</code> to
 * <code>Source</code> or <code>String</code>.
 * 
 * <br />
 * 
 * The following method is part of the <code>XMLLoading</code> class
 * from the example <a href="#xmlloadingexample">above</a>:
 * 
 * <pre style="border: 1px solid black">
    public static Source loadXMLFromResourceAsSource(Class clazz, String name)
            throws NoSuchResourceException, XMLLoadingException {
        return <span style="background-color: rgb(255,255,200)">XMLTools.documentToDOMSource</span>(
                loadXMLFromResourceAsDocument(clazz, name));
    }
 * </pre>
 * 
 * <h3>Validation</h3>
 * 
 * Both, <code>XMLUtilities</code> and <code>XMLTools</code> allows you to
 * validate specified XML file against specified Schema. The following class
 * shows you, how tu use the static variant:
 * 
 * <pre style="border: 1px solid black">
package global.sandbox.xmlutilities.demo;

import global.sandbox.xmlutilities.XMLTools;
import javax.xml.transform.Source;
import org.w3c.dom.Document;

public class SchemaValidator {
    
    public static void validateXML(Source doc, Source schema)
            throws SchemaValidatorException, ValidationException {
        String result;
        
        try {
<span style="background-color: rgb(255,255,200)">            result = XMLTools.validateXmlUsingSchema(doc, schema);</span>
        } catch (Exception ex) {
            throw new SchemaValidatorException(ex);
        }
        
        if (result != null) {
            throw new ValidationException(result);
        }
    }
    
    public static void validateXML(Document doc, Document schema)
            throws SchemaValidatorException, ValidationException {
        validateXML(
                XMLTools.documentToDOMSource(doc),
                XMLTools.documentToDOMSource(schema));
    }
    
    public static class SchemaValidatorException extends Exception {
        
        private static final long serialVersionUID = 1L;
        
        public SchemaValidatorException(Throwable cause) {
            super(cause);
        }
        
    }
    
    public static class ValidationException extends Exception {
        
        private static final long serialVersionUID = 1L;
        
        public ValidationException(String message) {
            super(message);
        }
        
    }
    
}
 * </pre>
 * 
 * <h3>XPath Evaluation</h3>
 * 
 * The following code shows how to easily evaluate XPath query. The method
 * <code>loadAttribute</code> evaluates specified query <em>(the query should
 * end with <code>@xxx</code>)</em> and tries to convert obtained
 * <code>Node</code> to <code>Attr</code>. We can also try to cast
 * <code>Node</code> to <code>Attr</code> and catch the
 * <code>ClassCastException</code>.
 * 
 * <pre style="border: 1px solid black">
package global.sandbox.xmlutilities.demo;

import global.sandbox.xmlutilities.NamespaceContextImpl;
import global.sandbox.xmlutilities.XMLTools;
import javax.xml.namespace.NamespaceContext;
import org.w3c.dom.Attr;
import org.w3c.dom.Element;
import org.w3c.dom.Node;

public class XPathEvaluation {
    
    final static NamespaceContext namespaces;
    
    static {
        final NamespaceContextImpl nspaces = new NamespaceContextImpl();
        nspaces.addNamespace(
                "ns",
                "http://hadrabap.googlepages.com/projects/xmlutilities/demo");
        
        namespaces = nspaces;
    }
    
    public static Attr loadAttribute(Element rootNode, String xPathQuery)
            throws XPathEvaluationException {
        Node node;
        try {
<span style="background-color: rgb(255,255,200)">            node = XMLTools.getFirstNodeForXPath(
                    xPathQuery,
                    rootNode,
                    namespaces);</span>
        } catch (Exception ex) {
            throw new XPathEvaluationException(ex);
        }
        
        if (node == null) {
            return null;
        }
        
        if (node.getNodeType() == Node.ATTRIBUTE_NODE) {
            return (Attr) node;
        } else {
            throw new XPathEvaluationException(
                    "Resulting node is not Attr, gotten "
                    + node.getNodeType());
        }
    }
    
    public static class XPathEvaluationException extends Exception {
        
        private static final long serialVersionUID = 1L;
        
        public XPathEvaluationException(String message) {
            super(message);
        }
        
        public XPathEvaluationException(Throwable cause) {
            super(cause);
        }
        
    }
    
}
 * </pre>
 * 
 * <h3>Transformations</h3>
 * 
 * <code>XMLUtilities</code> and <code>XMLTools</code> also simplify
 * transformations. They support <code>Source</code>-based and precompiled
 * templates.
 * 
 * <br />
 * 
 * The following code demonstrates how to use the transformation support
 * in <code>XMLTools</code>:
 * 
 * <pre style="border: 1px solid black">
package global.sandbox.xmlutilities.demo;

import global.sandbox.xmlutilities.XMLTools;
import org.w3c.dom.Document;

public class Transformations {
    
    public static Document transform(Document doc, Document xsl)
            throws TransformationsException {
        try {
<span style="background-color: rgb(255,255,200)">            return XMLTools.transformToDocument(
                    XMLTools.documentToDOMSource(xsl),
                    XMLTools.documentToDOMSource(doc));</span>
        } catch (Exception ex) {
            throw new TransformationsException(ex);
        }
    }
    
    public static class TransformationsException extends Exception {
        
        private static final long serialVersionUID = 1L;
        
        public TransformationsException(Throwable cause) {
            super(cause);
        }
        
    }
    
}
 * </pre>
 * 
 * <hr />
 * 
 * For more details please check the test cases.
 * 
 * <hr />
 * 
 * <h3>ChangeLog</h3>
 * 
 * <table border="1" cellpadding="5" cellspacing="0">
 *   <thead>
 *     <tr>
 *       <th>Version</th>
 *       <th>Changes</th>
 *     </tr>
 *   </thead>
 *   <tbody>
 *     <tr>
 *       <td>1.0</td>
 *       <td>
 *         <ul>
 *           <li>Initial release</li>
 *         </ul>
 *       </td>
 *     </tr>
 *     <tr>
 *       <td>1.1</td>
 *       <td>
 *         <ul>
 *           <li>Added support for Namespaces</li>
 *           <li>First public-domain release</li>
 *         </ul>
 *       </td>
 *     </tr>
 *   </tbody>
 * </table>
 * <hr />
 * 
 * <h3>TODO</h3>
 * 
 * <dl>
 *   <dt>Casted versions of <code>getFirstNodeForXPath</code></dt>
 *   <dd>
 *     current version provides only <code>Node</code>. It can try to cast
 *     to specialized Class such as <code>Element</code> or <code>Attr</code>.
 *     My approach is something like <code>getFirstNodeForXPathAsAttr</code>
 *     or <code>getFirstNodeForXPathAsElement</code>.
 *   </dd>
 *   <dt>more conversion tools</dt>
 *   <dd>
 *     currently, <code>Document</code> to <code>Source</code> is not available
 *   </dd>
 * </dl>
 */
package global.sandbox.xmlutilities;
